/*
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 */
package erwiki.api.event;

/**
 * WikiPageEvent indicates a change in the state or processing of a WikiPage. There are basically
 * two types of page events:
 * <dl>
 * <dt><b>Phase Boundary Events</b></dt>
 * <dd>Those considered as "beginning-of-phase", and those as "end-of-phase" events (as designated
 * by <tt>*_BEGIN</tt> and <tt>*_END</tt>), as generated by the WikiEngine. The phases include
 * pre-save, post-save, pre-translate, and post-translate.</dd>
 * <dt><b>In-Phase Events</b></dt>
 * <dd>In-phase events are generated as specific events from the PageEventFilter (or elsewhere), on
 * a per-listener basis. There may be many such events during a particular phase.</dd>
 * </dl>
 * <p>
 * E.g., a typical event sequence for the pre-translate phase would be:
 * </p>
 * <ol>
 * <li>PRE_TRANSLATE_BEGIN</li>
 * <li>PRE_TRANSLATE</li>
 * <li>PRE_TRANSLATE</li>
 * <li>...</li>
 * <li>PRE_TRANSLATE_END</li>
 * </ol>
 *
 * <h2>Notes</h2>
 *
 * <h3>Page Requested and Delivered Events</h3>
 * <p>
 * These two events are fired once per page request, at the beginning and after delivery of the page
 * (respectively). They are generated by the {@link org.apache.wiki.ui.WikiServletFilter}.
 * </p>
 *
 * <h3>Page Lock and Unlock Events</h3>
 * <p>
 * Page lock and unlock events occur only once during an editing session, so there are no begin and
 * end events. They are generated by the {@link org.apache.wiki.pages0.PageManager}.
 * </p>
 *
 * <h3>WikiPageEvents</h3>
 * <p>
 * Other WikiPageEvents include both <i>phase boundary</i> and <i>in-phase</i> events for saving,
 * pre- and post-translating content. These are very noisy event types, but are not fired unless a
 * listener is available. They are generated by the {@link org.apache.wiki.filters.FilterManager},
 * {@link org.apache.wiki.filters.PageEventFilter}, and potentially other implementing classes.
 * </p>
 *
 * <h3>Firing Order and Phase Boundaries</h3>
 * <p>
 * Note that due to the asynchronous nature of event processing, any threads spawned by such events
 * will not necessarily have completed during their specific phase; we can assume only that no more
 * events of that phase will be fired after its <tt>*_END</tt> event has been fired.
 * </p>
 */
public interface PageEvent extends WikiEvent {

	interface Topic {
		String DOMAIN = WikiEvent.Topic.DOMAIN + "/page";
		String ALL = DOMAIN + "/*";

		// PAGE LOCKING EVENTS ...

		/**
		 * Indicates a page lock event. This is based on events generated by
		 * {@link org.apache.wiki.pages0.PageManager}.
		 */
		String LOCK = DOMAIN + "/LOCK";

		/**
		 * Indicates a page unlock event. This is based on events generated by
		 * {@link org.apache.wiki.pages0.PageManager}.
		 */
		String UNLOCK = DOMAIN + "/UNLOCK";

		// PRE_TRANSLATE .........

		/**
		 * Indicates the beginning of all wiki pre-translate page events. This is based on events generated
		 * by {@link org.apache.wiki.filters.FilterManager}.
		 */
		String PRE_TRANSLATE_BEGIN = DOMAIN + "/PRE_TRANSLATE_BEGIN";

		/**
		 * Indicates a wiki pre-translate page event. This is based on events generated by
		 * {@link org.apache.wiki.filters.PageEventFilter}.
		 */
		String PRE_TRANSLATE = DOMAIN + "/PRE_TRANSLATE";

		/**
		 * Indicates the end of all wiki pre-translate page events. This is based on events generated by
		 * {@link org.apache.wiki.filters.FilterManager}.
		 */
		String PRE_TRANSLATE_END = DOMAIN + "/PRE_TRANSLATE_END";

		// POST_TRANSLATE ........

		/**
		 * Indicates the beginning of all wiki post-translate page events. This is based on events generated
		 * by {@link org.apache.wiki.filters.FilterManager}.
		 */
		String POST_TRANSLATE_BEGIN = DOMAIN + "/POST_TRANSLATE_BEGIN";

		/**
		 * Indicates a wiki post-translate page event. This is based on events generated by
		 * {@link org.apache.wiki.filters.PageEventFilter}.
		 */
		String POST_TRANSLATE = DOMAIN + "/POST_TRANSLATE";

		/**
		 * Indicates the end of all wiki post-translate page events. This is based on events generated by
		 * {@link org.apache.wiki.filters.FilterManager}.
		 */
		String POST_TRANSLATE_END = DOMAIN + "/POST_TRANSLATE_END";

		// PRE_SAVE ..............

		/**
		 * Indicates the beginning of all wiki pre-save page events. This is based on events generated by
		 * {@link org.apache.wiki.filters.FilterManager}.
		 */
		String PRE_SAVE_BEGIN = DOMAIN + "/PRE_SAVE_BEGIN";

		/**
		 * Indicates a wiki pre-save page event. This is based on events generated by
		 * {@link org.apache.wiki.filters.PageEventFilter}.
		 */
		String PRE_SAVE = DOMAIN + "/PRE_SAVE";

		/**
		 * Indicates the end of all wiki pre-save page events. This is based on events generated by
		 * {@link org.apache.wiki.filters.FilterManager}.
		 */
		String PRE_SAVE_END = DOMAIN + "/PRE_SAVE_END";

		// POST_SAVE .............

		/**
		 * Indicates the beginning of all wiki post-save page events. This is based on events generated by
		 * {@link org.apache.wiki.filters.FilterManager}.
		 */
		String POST_SAVE_BEGIN = DOMAIN + "/POST_SAVE_BEGIN";

		/**
		 * Indicates a wiki post-save page event. This is based on events generated by
		 * {@link org.apache.wiki.filters.PageEventFilter}.
		 */
		String POST_SAVE = DOMAIN + "/POST_SAVE";

		/**
		 * Indicates the end of all wiki post-save page events. This is based on events generated by
		 * {@link org.apache.wiki.filters.FilterManager}.
		 */
		String POST_SAVE_END = DOMAIN + "/POST_SAVE_END";

		// PAGE REQUESTS .........

		/**
		 * Indicates a wiki page request event (the start of a request). This is based on events generated
		 * by {@link org.apache.wiki.ui.WikiServletFilter}.
		 */
		String REQUESTED = DOMAIN + "/REQUESTED";

		/**
		 * Indicates a wiki page delivery event (the end of a request). This is based on events generated by
		 * {@link org.apache.wiki.ui.WikiServletFilter}.
		 */
		String DELIVERED = DOMAIN + "/DELIVERED";

		/**
		 * Indicates a wiki page delete event (the beginning of a delete request). This is based on events
		 * generated by {@link org.apache.wiki.ui.WikiServletFilter}.
		 *
		 * @since 2.4.65
		 */
		String DELETE_REQUEST = DOMAIN + "/DELETE_REQUEST";

		/**
		 * Indicates a page rename event. This is based on events generated by
		 * {@link org.apache.wiki.content.PageRenamer}.
		 */
		String RENAMED = DOMAIN + "/RENAMED";

		/**
		 * Indicates a wiki page deleted event (after the delete has been completed). This is based on
		 * events generated by {@link org.apache.wiki.ui.WikiServletFilter}.
		 */
		String DELETED = DOMAIN + "/DELETED";

		/** Indicates a wiki page reindex event (a page was changed when requested to a provided) */
		String REINDEX = DOMAIN + "/REINDEX";
	}

	String PROPERTY_PAGE_ID = "pageid";
	String PROPERTY_WIKI_CONTEXT = "wikicontext";

	String PROPERTY_OLD_PAGE_NAME = "oldpagename";
	String PROPERTY_NEW_PAGE_NAME = "newpagename";

}
